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README 


因为 工作 需要 学 习 Elasticsearch, 发 现 关 于 Spring-Data-Elasticsearch 的 文档 非常 少 , mp 
没有 对 应 官方 文档 的 中 译 版 本 ， 所 以 利用 早起 的 空闲 时 间 翻 译 一 下 。 基 于 
1.3.2.RELEASE 版 本 ， 如 果 对 Spring Data 的 其 他 模块 (eg:Spring Data Jpa) 比 较 了 解 ， 可 
以 直接 看 第 五 章 。 


英文 原版 地 址 :Spring Data Elasticsearch 


spring-data-elasticsearch 例子 : github 
spring-data-elasticsearch 与 Spring web 结 合 例子 :github 


下 载 地 址 : download 
阅读 地 址 : http://es.yemengying.com 
博客 地 址 : giraffe's home 


参考 文档 


e hitp://www.ibm.com/developerworks/cn/opensource/os-cn-spring-jpa/ 
e http://leo-suen.iteye.com/blog/1991305 


译 者 :giraffe0813 


项 目地 址 : github gitbook 


关键 字 约 定 : 


e domain class -> 域 对象 
e query builder -> 查询 构造 器 


AN b, 
个 绍 


说 明 : 由 于 英文 水 平 有 限 ， 且 对 querydsl 等 内 容 并 不 太 了 解 ， 可 能 存在 翻译 有 误 的 地 方 ， 请 见 


谅 ， 欢 迎 提 issue 


Created by giraffe0813 This is a book powered by GitBook. 
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Spring Data Elasticsearch 为 文档 的 存储 ， 查 询 ， 排 序 和 统计 提供 了 一 个 高 度 抽象 的 模 


板 。 在 使 用 中 ， 你 会 发 现 Spring Data Elasticsearch 和 Spring Data Solr/Mongodb 有 许多 
相似 之 处 。 
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项 目 元 数据 


e Version Control - https://github.com/spring-projects/spring-data-elasticsearch 


e Bugtracker - https://jira.spring.io/browse/DATAES 


Release repository - https://repo.spring.io/libs-release 


Milestone repository - https://repo.spring.io/libs-milestone 


Snapshot repository - https://repo.spring.io/libs-snapshot 





使 用 条 件 


需要 使 用 Elasticsearch 0.20.2 及 以 上 的 版 本 
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玩 转 Spring Data Repositories 


抽象 出 Spring Data repository 是 因为 在 开发 过 程 中 ， 常 常会 为 了 实现 不 同 持久 化 存储 的 数据 
访问 层 而 写 大 量 的 大 同 小 异 的 代码 。Spring Data repository 的 目的 就 是 要 大 幅 减 少 这 些 重复 
的 代码 。 


AS | wk T Spring Data repository 的 核心 概念 及 接口 。 本 章 的 内 容 来 自 Spring data 的 公 
共 模 块 ， 配 置 和 样 例 代 码 来 自 Java Persistence Api(JPA) 模 块 。 如 有 需要 ， 可 以 将 XML 
文件 的 命名 空间 调整 到 你 所 使 用 的 特定 模块 (eg:elasticsearch/mongo 等 等 )。 命 名 空间 参 
考 文档 酒 盖 了 所 有 支持 Repository API 的 Spring Data 模 块 的 XML 配置 。Repository 查 询 关 
键 字 说 明文 档 内 列 出 了 repository 支 持 的 查询 方法 的 关键 字 。 如 果 想 要 了 解 其 他 特定 模块 


的 详细 信息 ， 可 以 查询 指定 模块 的 参考 文档 。 


玩 转 Spring Data Repositories 


核心 概念 


Spring Data repository 抽 象 中 最 核心 的 接口 就 是 Repository( 显 而 易 见 的 哈 )。 该 接口 使 用 了 泛 
型 ， 需 要 提供 两 个 类 型 参数 ， 第 一 个 是 接口 处 理 的 域 对 象 类 型 ， 第 二 个 是 域 对 象 的 主键 类 

型 。 这 个 接口 常 被 看 做 是 一 个 标记 型 接口 ， 用 来 获取 要 操作 的 域 对 象 类 型 和 帮助 开发 者 识别 
继承 这 个 类 的 接口 。 在 Repository 的 基础 上 ，CrudRepository 接 口 提 供 了 针对 实体 类 的 复杂 的 
CRUD(8 HIN & E, 


Example 1.CrudRepository interface(CrudRepositoryf£ O) 


public interface CrudRepository<T, ID extends Serializable> 
extends Repository<T, ID» { 


«S extends T» S save(S entity); //1 


T findOne(ID primarykey); //2 
Iterable<T> findAll(); S 
Long count(); //4 
void delete(T entity); 7/7/15 


boolean exists(ID primaryKey); //6 


// .. more functionality omitted. 


.保存 实体 类 
.返回 指定 id 的 实体 类 
.返回 所 有 实体 类 
.返回 实体 类 的 数量 

. 删除 指定 实体 类 

.判断 指定 id 的 实体 类 是 否 存在 


OO P WN EB 





Spring Data 也 提供 了 一 些 针 对 特定 持久 化 技术 的 抽象 ， 例 如 JpaRepository 和 
MongoRepository. 3x #£#£0 14 4k%K T CrudRepository 











PagingAndSortingRepository 接 口 在 CrudRepository 的 基础 上 增加 了 一 些 方法 ， 使 开发 者 可 以 
方便 的 对 实体 类 进行 分 页 和 排序 。 


Example 2.PagingAndSortingRepository 


public interface PagingAndSortingRepository<T, ID extends Serializable> 
extends CrudRepository<T, ID» { 


Iterable<T> findAll(Sort sort); 


Page<T> findAll(Pageable pageable); 


在 分 页 长 度 为 20 的 基础 上 ， 想 要 获取 第 二 页 的 Use/ 数 据 ， 代 码 如 下 


PagingAndSortingRepository<User, Long> repository = // .. get access to a bean 
Page<User> users = repository.findAll(new PageRequest(1, 20)); 


IRT EKDA, ROLE A ot ETA WM count( ARMS) Aldelete( MPR) 77K. 


Example 3.Derived Count Query( 获 取 数 量 ) 


public interface UserRepository extends CrudRepository<User, Long> { 


Long countByLastname(String lastname); 


Example 3.Derived Delete Query( 删 除 ) 


public interface UserRepository extends CrudRepository<User, Long> { 
Long deleteByLastname(String lastname); 


List«User» removeByLastname(String lastname); 


查询 方法 


标准 的 CRUD( 增 删改 查 ) 功 能 都 要 使 用 查询 语句 来 查询 数据 库 。 但 通过 使 用 Spring Data, 
四 个 步骤 就 可 以 实现 。 


ri 


^N 


要 


1. 声 明 一 个 继承 Repository 接 口 或 其 子 接口 的 持久 层 接 口 。 并 标明 要 处 理 的 域 对 象 类 型 及 其 主 


键 的 类 型 (在 下 面 的 例子 中 ， 要 义理 的 域 对 象 是 Person， 其 主键 类 型 是 Long) 


interface PersonRepository extends Repository<Person, Long> {...} 


2. 在 接口 中 声明 查询 方法 (spring 会 为 其 生成 实现 代码 ) 


interface PersonRepository extends Repository<Person, Long> { 
List<Person> findByLastname(String lastname); 


3. 让 Spring 创 建 对 这 些 接 口 的 代理 实例 。 
通过 JavaConfig 


import org.springframework.data.jpa.repository.config.EnableJpaRepositories; 


@EnableJpaRepositories 
class Config {} 


通过 XML 配置 


<?xml version="1.0" encoding="UTF-8"?> 
<beans xmlns="http://www.springframework.org/schema/beans" 
xmins:xsi="http://www.w3.org/2001/XMLSchema- instance" 
xmlns:jpa="http://www.springframework.org/schema/data/jpa" 
xsi:schemaLocation-"http://www.springframework.org/schema/beans 
http://www.springframework.org/schema/beans/spring-beans.xsd 
http://www.springframework.org/schema/data/jpa 
http://www. springframework.org/schema/data/jpa/spring-jpa.xsd"> 


<jpa:repositories base-package="com.acme.repositories"/> 


</beans> 


这 里 使 用 JPA 的 命名 空间 作为 例子 ， 需 要 根据 实际 使 用 的 模块 更 改 命名 空间 ， 上 比如 可 以 改 为 
mongodb 等 等 。 需 要 注意 的 是 ， 在 使 用 JavaConfig 时 ， 如 果 需 要 自 定 义 打 描 的 包 而 不 是 使 用 


其 默认 值 ， 可 以 利用 注解 @EnableJpaRepositories 的 basePackage 属 性 。 具 体 使 用 方式 如 下 : 


@EnableJpaRepositories(basePackages = "com.cshtong")// €^ & 


@EnableJpaRepositories(basePackages = {"com.cshtong.sample.repository", "com.cshtong.towe 


: 一 CH 








4. 注 入 repository 实 例 ， 并 使 用 


public class SomeClient { 


@Autowired 


private PersonRepository repository; 


public void doSomething() { 


List<Person> persons = repository.findByLastname("Matthews"); 


这 一 部 分 会 在 之 后 详细 解释 


repository& L15E 3L 


在 第 一 步 中 我 们 定义 了 一 个 针对 特定 域 对 象 的 repository 接 口 ， 接 口 继承 了 Repository 接 口 并 
且 标 明了 域 对 象 类 型 及 其 主键 类 型 。 如 果 想 要 暴露 CRUD 方 法 可 以 不 继承 Repository 接 口 ， 直 
接 继 承 CrudRepository 接 口 即 可 。 


调整 repository 定 义 


通常 情况 下 ， 我 们 的 repository 接 口 会 继承 Repository, CrudRepository 或 
PagingAndSortingRepository 接 口 。 但 是 ， 如 果 不 想 通过 extend 关 键 字 继 承 Spring Data 的 接 
口 ， 还 可 以 采用 在 自 定义 的 repository 接 口上 加 注解 的 方式 ， 两 种 方式 是 等 价 的 。 例 子 如 下 : 


public interface UserDao extends Repository«AccountInfo, Long>{...} 


@RepositoryDefinition(domainClass = Person, idClass = Long.class) 
public interface PersonRepository {...} 


此 外 ， 继 承 CrudRepository 接 口 ， 会 为 操作 域 对 象 提 供 了 一 组 可 立即 使 用 的 方法 。 如 果 开 发 
者 不 想 暴 露 CrudRepository 接 口 的 全 部 方法 ， 只 需 简单 的 将 需要 的 方法 复制 到 自己 的 
repository 接 口中 。 





这 让 我 们 可 以 在 Spring Datade Repository 的 基础 上 定义 自己 的 抽象 接口 














Example 5.Selectively exposing CRUD methods( 选 择 性 暴露 方法 ) 


@NoRepositoryBean 
interface MyBaseRepository<T, ID extends Serializable> extends Repository<T, ID> { 


T findOne(ID id); 


T save(T entity); 
} 


interface UserRepository extends MyBaseRepository<User, Long» { 


User findByEmailAddress(EmailAddress emailAddress); 


} 


在 上 面 的 代码 中 ， 我 们 先 定义 了 一 个 公共 的 基础 接口 MyBaseRepository， 并 提供 findOne 和 
save 两 个 方法 。 接 着 声明 一 个 UserRepository 的 接口 并 继承 基础 接口 MyBaseRepository， 所 
以 UserRepository 拥 有 保存 User， 根 据 id 查 找 user 和 根据 邮箱 地 址 查找 User 三 个 方法 。 


注意 ， 中 间 过 渡 的 接口 MyBaseRepository 上 加 了 NoRepositoryBean 注 解 ， 这 个 注解 是 告 
i Spring Data 不 要 为 这 个 接口 创建 repository 代 理 实例 。 


定义 查询 方法 


通过 方法 名 ，Spring Data 有 两 种 方式 获得 开发 者 的 查询 意图 。 一 是 直接 解析 方法 名 ， 二 是 使 
用 @Query 创 建 的 查询 。 那 么 到 底 使 用 哪 种 方式 呢 ? Spring Data 有 一 套 策略 来 决定 创建 的 查 
询 。 


查询 策略 


Spring Data repository 使 用 下 面 的 一 套 策略 来 决定 最 后 创建 的 查询 。 可 以 通过 配置 XML 中 的 
query-loop-strategy 属 性 或 Javaconfig 中 Enable${store}Repositories 注 解 的 
queryLookupStrategy 属 性 来 调整 策略 。 某 些 特定 的 数据 存储 可 能 不 支持 所 有 策略 。 


e CREATE 通过 解析 方法 名 构建 查询 ， 会 删除 方法 名 的 某 些 前 级 (eg:findBy)， 并 解析 剩 下 
的 部 分 ， 会 在 下 一 节 创 建 查 询 中 详细 讲 。 

e USE DECLARED QUERY 如 果 方 法 通过 (Query 指定 了 查询 语句 ， 则 使 用 该 语句 创建 
Query ` 如 果 没 有 ， 则 查找 是 否定 义 了 符合 条 件 的 Named Query， 如 果 找 到 ， 则 使 用 该 
命名 查询 ; 如 果 两 者 都 没有 找到 ， 则 抛 出 异常 。 使 用 @Query 声 明 查 询 语 句 的 例子 如 下 : 


/ /使 
/ 


A Quer yt f 
@Query ("select a from AccountInfo a where a.accountId = 71") 
public AccountInfo findByAccountId (Long accountId) ; 


e CREATE IF NOT FOUND( 默 认 ) 结合 了 CREATE 和 USE DECLARED QUERY 两 种 策 
略 , 会 先 党 试 查找 声明 好 的 查询 ， 如 果 没 有 找到 ， 就 按照 解析 方法 名 的 方式 构建 查询 。 这 
是 默认 的 查询 策略 ， 如 果 不 更 改 配置 ， 会 一 直 使 用 这 种 策略 构建 查询 。 这 种 策略 支持 通 
过 方法 名 快速 定义 一 个 查询 ， 也 人 允许 引入 声明 好 的 查询 。 


创建 查询 


Spring Data repository 自 带 了 一 个 非常 有 用 的 查询 构造 器 。 它 会 从 方法 名 中 去 掉 类 

似 find..By,read...By,query...By,count...By 之 类 的 前 级 ， 然 后 解析 剩余 的 名 字 。 我 们 也 可 以 在 

方法 名 中 加 入 更 多 的 表达 式 ， 上 比如 查询 时 需要 distinct 约 束 ,那么 在 方法 名 中 加 入 Distinct 即 可 。 
方法 名 中 的 第 一 个 By 是 一 个 分 解 符 ， 代 表 着 查询 语句 的 开始 ， 我 们 可 以 用 And 或 Or 来 将 多 个 

查询 条 件 关 联 起 来 。 


Example 6.Query creation from method names( 通 过 方法 名 创建 查询 ) 


public interface PersonRepository extends Repository<User, Long> { 
List<Person> findByEmailAddressAndLastname(EmailAddress emailAddress, String lastname); 
// Enables the distinct flag for the query 


// 在 查询 中 使 用 distinct 约 束 
List«Person» findDistinctPeopleByLastnameOrFirstname(String lastname, String firstname) 


























List«Person» findPeopleDistinctByLastnameOrFirstname(String lastname, String firstname) 


// Enabling ignoring case for an individual property 
// 忽略 大 小 写 在 方法 名 中 加 入 IgnoreCase 
List«Person» findByLastnameIgnorecase(String lastname); 








// Enabling ignoring case for all suitable properties 
// 所 有 属性 都 忽略 大 小 写 在 方法 名 中 加 入 AllIgnoreCase 
List«Person» findByLastnameAndFirstnameAllIgnoreCase(String lastname, String firstname) 
































// Enabling static ORDER BY for a query 
// 排序 在 方法 名 中 加 入 OrderBy 
List<Person> findByLastnameOrderByFirstnameAsc(String lastname); 











List<Person> findByLastnameOrderByFirstnameDesc(String lastname); 


} 
| 


对 方法 名 的 解析 结果 取决 于 实际 要 操作 的 数据 库 /搜索 引擎 是 什么 。 另外， 还 有 一 些 普通 的 问 
题 要 注意 : 


e 在 方法 名 中 ， 可 以 使 用 Ana 和 Or 连接 多 个 属性 。 除 此 之 外 还 可 以 使 
用 Between,LessThan,GreaterThan,Like 等 等 ， 不 同 数据 库 支持 的 连接 符 是 不 一 样 的 ， 需 
要 查看 相关 文档 

e 可 以 使 用 lgnoreCase 来 忽略 单个 属性 的 大 小 写 ， 上 比如 findByLastnamelgoreCase, 也 可 以 
使 用 AlllgnoreCase 来 忽略 全 部 属性 的 大 小 写 。 前 提 是 ， 实 际 选择 的 数据 库 / 搜 索引 擎 支 
持 。 

e 可 以 使 用 OrderBy 来 对 相关 属性 进行 排序 。 具 体 是 升序 还 是 降序 ， 是 通过 Asc 和 Desc 控 制 
的 。 如 果 想 了 解 动态 排序 ， 请 看 处 理 特殊 参数 。 


属性 表达 式 


接 下 来 我 们 来 看 看 属性 表达 式 。 在 之 前 的 例子 中 ， 属 性 表达 式 只 涉及 到 被 管理 的 实体 类 的 直 
接 属性 ， 在 创建 查询 时 我 们 已 经 确保 解析 出 的 属性 是 被 管理 实体 类 的 属性 之 一 。 实 际 上 ， 我 
们 可 以 定义 佬 套 属性 。 假 设 Person 类 有 一 个 Address，Address 中 又 有 ZipCode。 在 这 种 情况 
下 ， 下 面 方 法 的 方法 名 会 通过 x.address.zipCode 来 检索 属性 。 


List<Person> findByAddressZipCode(ZipCode zipCode); 


Spring Data 的 查询 构造 器 会 先 把 AddressZipCode 当 做 一 个 整体 ， 检 查 其 是 不 是 实体 类 的 一 个 
属性 。 如 果 是 ， 就 使 用 这 个 属性 。 如 果 不 是 ， 会 按照 驼峰 式 从 右 向 左 进行 分 割 ， 再 进行 属性 
匹配 。 在 上 面 的 例子 中 ， 会 业 AqdressZipCode 分 为 AddressZip 和 Code。 如 果 第 一 次 分 割 之 后 
还 没有 找到 相 匹 配 的 属性 ， 构 造 器 会 左 移 分 割 点 重新 进行 分 割 ， 分 为 Address 和 ZipCode， 并 
继续 解析 是 否 有 相 匹 配 的 属性 。 在 大 多 数 情 况 下 ， 构 造 器 都 能 够 正确 的 解析 出 相 匹 配 的 属 
性 。 但 在 某 些 特殊 情况 下 ， 可 能 会 选择 了 错误 的 属性 。 假 设 Person 类 中 除了 address 外 ， 还 有 
一 个 addressZip 属 性 。 那 么 构造 器 会 在 第 一 次 分 割 后 就 匹配 到 相应 的 属性 ， 然 后 报错 ( 因 
为 addressZip 中 没有 code 属 性 ) 。 为 了 避免 的 解析 的 歧义 问题 ， 我 们 可 以 在 方法 名 中 使 

用 '_' 符 号 来 显 式 的 表达 意图 ， 更 改 后 的 方法 名 如 下 : 


List<Person> findByAddress ZipCode(ZipCode zipCode); 


因为 构造 器 已 经 将 下 划 线 作为 保留 字符 ， 所 以 强烈 建议 开发 者 遵循 标准 的 Java 命 名 规范 ， 不 
要 在 属性 名 中 使 用 下 划 线 ， 采 用 驼峰 式 命名 。 


处 理 特殊 参数 


通过 上 面 的 例子 ， 我 们 知道 可 以 方便 的 通过 定义 方法 的 参数 来 处 理 查 询 中 的 参数 。 除 此 之 
外 ， 我 们 还 可 以 为 方法 添加 某 些 特定 类 型 的 参数 (如 :Pageable 和 Sort) 来 动态 的 在 查询 中 添加 
分 页 和 排序 。 


Example 7. Using Pageable, Slice and Sort in query methods( 查 询 中 进行 分 页 和 排序 ) 


Page<User> findByLastname(String lastname, Pageable pageable); 
Slice<User> findByLastname(String lastname, Pageable pageable); 
List<User> findByLastname(String lastname, Sort sort); 


List«User» findByLastname(String lastname, Pageable pageable); 


第 一 个 例子 中 我 们 向 方法 传递 一 个 org.springframework.qdata.domain.Pageable 的 实例 来 为 查 
询 动态 的 添加 分 页 ， 返 回 的 Page 对 象 中 包含 元 素 总 数 和 当前 页 的 数据 。 其 中 的 元 素 总 数 是 通 
过 Spring Data 自 动 触发 的 一 个 count 查 询 获得 的 。 但 是 count 查 询 有 时 会 降低 一 定 的 性 能 ， 所 
以 在 不 需要 总 数 时 ， 我 们 可 以 使 用 Slice 来 代替 Page。Slice 仅 仅 可 以 知道 是 否 有 可 用 的 下 一 个 
Slice, 排序 操作 也 可 以 通过 Pageable 实 例 来 处 理 。 但 如 果 你 需要 的 只 是 排序 ， 只 需要 为 方法 
添加 org.springframework.data.domain.Sort 类 型 的 参数 即 可 。 我 们 也 可 以 只 简单 的 返回 一 个 
list， 这 时 就 不 会 执行 Count 查 询 ， 只 查询 给 定 范 围 的 实体 类 。 

















如 果 想 知道 总 共有 多 少 页， 就 必须 触发 一 个 额外 的 count 查 询 


限定 查询 结果 集 大 小 


Spring Data 人 允许 开发 者 使 用 first 和 top 关 键 字 对 返回 的 查询 结果 集 大 小 进行 限定 。fisrt 和 top 需 
要 跟着 一 个 代表 返回 的 结果 集 的 最 大 大 小 的 数字 。 如 果 没 有 跟着 一 个 数字 ， 那 么 返回 的 结 
集 大 小 默认 为 1。 


Example 8.Limiting the result size of query with Top and First( 利 用 first 和 top 限 制 返回 的 结果 
集 大 小 ) 

User findFirstByOrderByLastnameAsc(); 

User findTopByOrderByAgeDesc(); 

Page<User> queryFirst10ByLastname(String lastname, Pageable pageable); 

Slice<User> findTop3ByLastname(String lastname, Pageable pageable); 

List«User» findFirstiOByLastname(String lastname, Sort sort); 


List«User» findTop10ByLastname(String lastname, Pageable pageable); 


限制 结果 集 的 表达 式 还 支持 Distinct 关 键 字 。 并 且 ， 当 返回 的 结果 集 大 小 限制 为 1 时 ，Spring 
Data 支 持 将 返回 结果 包装 到 Optional(java 8 新 增 ， 这 是 一 个 可 以 为 null 的 容器 对 象 。 如 果 值 存 
在 则 isPresent() 方 法 会 返回 true， 调 用 get() 方 法 会 返回 该 对 象 ) 之 中 ， 例 子 如 下 : 


Optional<User> findFirstByOrderByLastnameAsc(); 


在 查询 用 page 和 slice 来 进行 分 页 查询 的 情况 下 ， 同 样 可 以 使 用 first 和 top 来 对 结果 集 大 小 进行 
限制 。 


注意 ， 如 果 在 使 用 Sort 人 参数 对 查询 结果 进行 排序 的 基础 上 加 上 对 结果 集 大 小 的 限制 ， 就 
可 以 轻易 的 获得 最 大 的 K 个 元 素 或 最 小 的 K 个 元 素 。 


利用 Stream( 流 ) 处 理 查询 结果 


我 们 可 以 使 用 Stream 作 为 返回 类 型 可 以 对 查询 结果 进行 逐个 处 理 。 
Example 9. Stream the result of a query with Java 8 Stream(stream 查 询 结 末 ) 


@Query("select u from User u") 
Stream<User> findAllByCustomQueryAndStream(); 





Stream<User> readAllByFirstnameNotNull(); 
@Query("select u from User u") 


Stream<User> streamAllPaged(Pageable pageable); 


一 个 Stream 中 可 能 包含 底层 数据 存储 的 特定 资源 ， 所 以 在 使 用 后 必须 关闭 。 可 以 通过 调 
用 close() 方 法 ， 也 可 以 使 用 java 7 中 的 try-with-resources 块 


Example 10. Working with a Stream result in a try-with-resources block( 在 块 中 使 用 Stream) 


try (Stream<User> stream = repository.findAllByCustomQueryAndStream()) { 
stream.forEach(..); 


} 


目前 ， 不 是 所 有 的 Spring Data 模 块 都 支持 将 Stream 作 为 返回 类 型 


异步 处 理 查询 结果 


Spring Data repository 中 的 查询 可 以 异步 执行 ， 参 考 Spring 执 行 异 步 方法 。 这 意味 着 方法 可 以 
在 被 调用 时 立刻 返回 ， 而 真正 的 查询 执行 会 被 当做 一 个 任务 提交 到 Spring 的 TaskExecutor。 


@Async 
Future<User> findByFirstname(String firstname); //1 


@Async 
CompletableFuture<User> findOneByFirstname(String firstname); //2 


@Async 
ListenableFuture<User> findOneByLastname(String lastname); //3 


1. 使 用 java.util.concurrent .Future 作 为 返回 类 型 。 
2 .使 用 Java 8 中 的 java.util.concurrent.CompletableFuture 作 为 返回 类 型 。 
3. 使 用 org.springframework.util.concurrent.ListenableFuture 作 为 返回 类 型 


创建 repository 实 例 


这 一 部 分 将 介绍 如 何 为 定义 好 的 repository 接 口 创 建 实 例 和 bean。 一 种 方式 是 使 用 Spring Data 
模块 下 支持 repository 配 置 的 Spring 命名 空间 。 不 过 ， 通 常 推 荐 使 用 JavaConfig 风 格 的 配置 。 


XML ër e 


每 个 Spring Data 模 块 都 包含 一 个 repository 元 素 ， 通 过 这 个 元 素 开 发 者 可 以 轻松 的 定义 spring 
扫描 包 的 路 径 。 


Example 11.Enabling Spring Data repositories via XML 


<?xml version="1.0" encoding="UTF-8"?> 
<beans:beans xmlns:beans="http://www.springframework.org/schema/beans" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema- instance" 
xmlns="http://www.springframework.org/schema/data/jpa" 
xsi:schemaLocation="http://www.springframework.org/schema/beans 
http://www. springframework.org/schema/beans/spring-beans. xsd 
http://www. springframework.org/schema/data/jpa 
http://www. springframework.org/schema/data/jpa/spring-jpa.xsd"> 


<repositories base-package-"com.acme.repositories" /> 


</beans:beans> 


在 上 面 的 例子 中 ，Spring 扫 描 base-package 中 指定 的 路 径 及 其 包含 的 所 有 包 ， 检 测 出 继承 
Repository 或 者 其 子 接口 的 接口 。 每 找到 一 个 接口 ，FactoryBean 会 创建 对 应 的 代理 去 义理 查 
询 方法 的 调用 。 每 个 注册 的 bean 的 名 称 都 来 自 于 接口 名 称 ， 例 如 : UserRepository 将 会 被 注 
册 为 userRepository。base-package 人 允许 使 用 通配符 来 定义 打 描 路 径 。 


使 用 过 滤器 


默认 情况 下 ，Spring 会 找到 配置 路 径 下 的 所 有 接口 并 为 其 创建 一 个 bean 实 例 。 但 有 些 情况 下 
开发 者 可 能 想 要 更 细致 的 控制 创建 bean 实 例 的 接口 。 这 时 候 ， 可 以 在 元 素 中 使 用 和 。 这 些 元 
素 的 详细 用 法 可 以 参考 spring 参 考 文 档 。 下 面 的 配置 就 是 排除 某 些 特定 接口 的 例子 : 


Example 12. Using exclude-filter element( 使 用 exclude-filter 元 素 ) 


<repositories base-package="com.acme.repositories"> 
<context:exclude-filter type="regex" expression=".*SomeRepository" /> 
</repositories> 


上 面 的 配置 排除 了 所 有 以 SomeRepository 结 尾 的 接口 。 


JavaConfig 


我 们 也 可 以 使 用 JavaConfig 类 中 的 注解 @Enable${store}Repositories 来 配置 打 描 包 的 路 径 。 
在 实际 开发 中 ， 要 针对 不 同 的 持久 化 存储 蔡 换 不 同 的 ${store}。 下 面 是 使 用 JavaConfig 配 置 的 
一 个 例子 : Example 13. Sample annotation based repository configuration 


@Configuration 
@EnableJpaRepositories("com.acme.repositories") 
class ApplicationConfiguration { 


@Bean 


public EntityManagerFactory entityManagerFactory() { 
VL EN 


} 
} 


在 上 面 的 例子 中 使 用 了 针对 Jpa 的 注解 ， 需 要 根据 实际 使 用 的 存储 修改 。 同 样 地 ， 使 用 的 
存储 不 同 ， 定 义 的 EntityManagerFactorybean 也 不 同 。 具 体 请 查看 针对 指定 存储 配置 的 
文档 。 


独立 使 用 


开发 者 可 以 在 脱离 Spring 容器 的 情况 下 利用 RepositoryFactory 来 使 用 Spring Data 
repository( 比 如 在 CDI 环 境 下 )， 但 仍然 需要 将 某 些 Spring 的 依赖 包 加 到 classpath 中 。 


Example 14. Standalone usage of repository factory (独立 使 用 ) 


RepositoryFactorySupport factory = // Instantiate factory here( 初 始 化 factory ) 
UserRepository repository = EM. DOR USER OD class); 


自 定 义 repository 实 现 


在 开发 过 程 中 ， 常 常 需 要 为 一 些 repository 方 法 添加 自 定 义 的 实现 。Spring Data repository? 
许 开 发 者 自 定义 repository 方 法 。 


为 单一 的 repositories 添 加 自 定 义 方 法 


为 了 通过 自 定 义 方 法 来 丰富 repository， 首 先 要 定义 一 个 接口 和 一 个 接口 的 实现 类 。 


Example 15. Interface for custom repository functionality( 自 定义 接口 ) 


interface UserRepositoryCustom { 
public void someCustomMethod(User user); 


} 


Example 16. Implementation of custom repository functionality (33 [18^] 3z 5i 3€ ) 


class UserRepositoryImpl implements UserRepositoryCustom { 
public void someCustomMethod(User user) { 
// Your custom implementation 


} 
} 


接口 的 实现 类 名 字 后 缀 必须 为 Imp/ 才 能 在 扫描 包 时 被 找到 。 


实现 类 本 身 并 不 依赖 于 Spring Data， 就 是 一 个 普通 的 Srping 的 bean， 所 以 可 以 是 用 标准 的 依 
赖 注入 在 其 中 注入 其 它 相 关 的 bean， 上 比如 JdbcTemplate 等 等 。 


Example 17. Changes to the your basic repository interface( 修 改 基 础 的 repository 接 口 ) 


interface UserRepository extends CrudRepository<User, Long>, UserRepositoryCustom { 


// Declare query methods here 


} 


上 面 代 码 在 让 标准 的 repository 接 口 继承 了 自 定义 的 接口 ， 将 标准 的 CRUD 和 自 定义 的 方法 结 


BCS 


在 使 用 Xml 配 置 时 ，Spring 框 架 会 自动 检测 指定 包 路 径 下 的 实现 类 。 实 现 类 的 后 级 必须 满足 属 
性 repository-impl-postfix 的 定义 ， 默 认 后 级 是 /mpl。 


<repositories base-package="com.acme.repository" /> 


<repositories base-package="com.acme.repository" repository-impl-postfix="FooBar" /> 


在 第 一 个 配置 中 ，spring 会 找到 类 com.acme.reposijtory UserRepositorylmpl, MERZTEL 
置 中 ，spring 会 尝试 查找 com.acme.repository.UserRepositoryFooBar 类 


ATE 


上 面 的 例子 使 用 了 基于 注解 的 配置 来 自动 装载 。 如 果 自 定义 的 实现 类 需要 特殊 的 装载 ， 也 可 
以 手动 的 声明 一 个 bean, 名 字 要 遵循 上 一 节 定 义 的 命名 规范 。 


Example 19. Manual wiring of custom implementations( 人 工装 载 自 定义 的 实现 类 ) 


tories base-package-"com.acme.repository" /> 





:bean id="userRepositoryImpl" class="..."> 





为 所 有 的 repositories 添 加 自 定 义 方 法 


如 果 想 要 给 为 所 有 的 repository 接 口 增加 一 个 方法 ， 那 么 之 前 的 方法 是 不 可 行 的 。 为 了 给 所 有 
的 repository 添 加 自 定义 的 方法 ， 开 发 者 首先 需要 定义 一 个 中 间 过 渡 的 接口 。 


Example 20. An interface declaring custom shared behavior( 定 义 中 间接 口 声 明 ) 


@NoRepositoryBean 
public interface MyRepository<T, ID extends Serializable> 
extends PagingAndSortingRepository<T, ID> { 


void sharedCustomMethod(ID id); 


} 


现在 ， 开 发 者 的 其 他 repository 接 口 需 要 继承 定义 的 中 间接 口 而 不 是 继承 Repository 接 口 。 接 
下 来 需要 为 这 个 中 间接 口 创建 实现 类 。 这 个 实现 类 是 基于 Repository 中 的 基 类 的 (不 同 的 持久 
化 存储 继承 的 基 类 也 不 相同 ， 这 里 以 Jpa 为 例 )， 这 个 类 会 被 当做 repository 代 理 的 自 定义 类 来 
执行 。 Example 21. Custom repository base class( 自 定义 reposotory 基 类 ) 


public class MyRepositoryImpl<T, ID extends Serializable> 





extends SimpleJpaRepository<T, ID> implements MyRepository<T, ID> { 


private final EntityManager entityManager; 


public MyRepositoryImpl(JpaEntityInformation entityInformation,EntityManager entityMana 
super(entityInformation, entityManager); 


// Keep the EntityManager around to used from the newly introduced methods. 
this.entityManager = entityManager; 


} 


public void sharedCustomMethod(ID id) { 


// implementation goes here 





Spring 中 命名 空间 默认 会 为 base-package 下 所 有 的 接口 提供 一 个 实例 。 但 MyRepository 只 是 
作为 一 个 中 间接 口 ， 并 不 需要 创建 实例 。 所 以 我 们 可 以 使 用 @NoRepositoryBean 注 解 或 将 其 
排除 在 base-package 的 配置 中 


最 后 一 步 是 使 用 JavaConfig 或 Xml 配置 这 个 自 定义 的 repository 基 类 。 


Example 22. Configuring a custom repository base class using JavaConfig(f& FH JavaConfig 
ic repository 3 ) 


@Configuration 
@EnableJpaRepositories(repositoryBaseClass = MyRepositoryImpl.class) 
class ApplicationConfiguration { .. } 

也 可 使 用 Xml 的 方式 配置 。 


Example 23. Configuring a custom repository base class using XML( 使 用 xml 配 置 自 定义 
repositoryd& 3k ) 


«repositories base-package="com.acme.repository" 
repository-base-class="...MyRepositoryImpl" /> 


扩展 Spring Data 


这 一 章 将 介绍 如 何 把 Spring Data 扩 展 到 其 他 的 框架 中 。 接 下 来 让 我 们 看 看 如 何 将 Spring Data 
整合 到 Spring MVC 中 。 


WEB 支 持 


Spring Data 带 有 很 多 的 web 支 持 。 要 使 用 它们 ， 需 要 在 classpath 中 加 入 Spring MVC 的 jar 包 ， 
有 的 还 需要 整合 Spring HATEOAS。 通 常情 况 下 ， 只 需 在 JavaConfig 的 配置 类 中 使 
FA@EnableSpringDataWebSupporti= ## B n] 


Example 24. Enabling Spring Data web support( 使 用 Spring Data 的 web 支 持 ) 


@Configuration 
@EnablewebMvc 
@EnableSpringDataWebSupport 
class WebConfiguration { } 


@EnableSpringDataWebSupport 注 解 会 注册 一 些 组 件 ， 我 们 会 在 之 后 讨论 。 它 同样 也 会 去 检 
测 classpath 中 的 Spring HATEOAS, 并 且 注 册 他 们 。 


如 果 不 想 通过 JavaConfig 开 启 web 支 持 ， 也 可 以 使 用 xml 配 置 ， 将 SpringDataWebSupport 和 
HateoasAwareSpringDataWebSupport 注 册 为 Spring 的 bean。 


Example 25. Enabling Spring Data web support in XML( 使 用 xml 配 置 ) 


«bean class="org.springframework.data.web.config.SpringDataWebConfiguration" /> 


[f you're using Spring HATEOAS as well register this one *instead* of the former 


«bean class="org.springframework.data.web.config.HateoasAwareSpringDataWebConfiguration" 





基础 的 web 支 持 
上 面 的 配置 会 注册 一 些 基 础 组 件 : 


e DomainClassConverter{#Spring MVC 可 以 从 请 求 参数 或 路 径 变 量 中 解析 repository 管 理 
的 域 对 象 的 实例 。 

e HandlerMethodArgumentResolver.{#Spring mvc 能 从 请 求 参数 来 解析 Pageable 和 Sort 实 
例 


DomainClassConverter 


DomainClassConverter 允许 开发 者 在 SpringMVC 控 制 层 的 方法 中 直接 使 用 域 对 象 类 型 
(Domain types), 而 无 需 通 过 repository 手 动 查找 这 个 实例 。 


Example 26. ASpring MVC controller using domain types in method signatures (在 Spring 
MVC 控 制 层 方法 中 直接 使 用 域 对 象 类 型 ) 


@Controller 
en 
public class UserController { 


@RequestMapping("/{id}") 
public String showUserForm(@PathVariable("id") User user, Model model) { 


model.addAttribute("user", user); 
return "userForm"; 


上 面 的 方法 直接 接收 了 一 个 User 对 象 ,开发 者 不 需要 做 任何 的 搜索 操作 ,转换 器 会 自动 将 路 径 变 
量 id 转 为 User 对 象 的 id, 并 且 调 用 了 findOne() 方 法 查询 出 User 实 体 。 


注意 :当前 的 Repository 必须 实现 CrudRepository 


HandlerMethodArgumentResolver 


个 配置 同时 注册 了 PageableHandlerMethodArgumentResolver 和 和 
ee E Pageable 和 
Sort 作 为 参数 。 Example 27. Using Pageable as controller method argument (在 controller 中 
使 用 Pageable 作 为 参数 ) 


@Controller 
Sn 
public class UserController { 


@Autowired UserRepository repository; 


@RequestMapping 
public String showUsers(Model model, Pageable pageable) { 


model.addAttribute("users", repository.findAll(pageable)); 
return "users"; 


通过 上 面 的 方法 定义 ，Spring MVC 会 使 用 下 面 的 默认 配置 尝试 从 请 求 参 数 中 得 到 一 个 
Pageable 的 实例 。 Table 1. Request parameters evaluated for Pageable instances page( 由 
于 构造 Pageable 实 例 的 请 求 参 数 ) 


参数 作用 


page ” 想 要 获取 的 页 数 ， 默 认为 0 
size 获取 页 的 大 小 ， 默 认为 20 


需要 排序 的 属性 ， 格 式 为 property,property(,ASC/DESC), 默 认 升 序 排序 。 支 持 多 
个 字段 排序 ， 比 如 ?sort=firstname&sort=/lastname,asc 


如 果 开 发 者 想 要 自 定义 分 页 或 排序 的 行为 ， 可 以 继承 SpringDataWebConfiguration 
或 HATEOAS-enabledq， 并 重 写 pageableResolver() 或 sortResolver() 方 法 ， 引 入 自 定义 的 配置 
文件 来 代替 使 用 @Enable- 注 解 。 


开发 者 也 可 以 针对 多 个 表 定 义 多 个 Pageable 或 Sort 实 例 ,需要 使 用 Spring 的 @Qualifier 注 解 来 
区 分 它们 。 并 且 请 求 参数 名 要 带 有 $f{qualifier} 的 前 经。 例子 如 下 : 


public String showUsers(Model model, 
@Qualifier("foo") Pageable first, 
@Qualifier("bar") Pageable second) {...} 


请 求 中 需要 带 有 foo_page 和 bar_page 等 参数 。 


默认 的 Pageable 相 当 于 new PageRequest(0, 20)， 但 开发 者 可 以 在 Pageable 参 数 上 使 
用 @PageableDefaults 来 自 定义 。 


超 媒 体 分 页 


Spring HATEOAS 有 一 个 PagedResources 类 , 它 丰富 了 Page 实 体 以 及 一 些 让 用 户 更 容易 导航 
到 资源 的 链接 。Page 转 换 到 PagedResources 是 由 一 个 实现 了 Spring HATEOAS 
ResourceAssembler 接 口 的 实现 类 :PagedResourcesAssembler 提 供 转换 的 。 Example 28. 
Using a PagedResourcesAssembler as controller method argument( 使 用 
PagedResourcesAssembler 当 做 方法 参数 ) 


@Controller 
class PersonController { 


@Autowired PersonRepository repository; 


@RequestMapping(value = "/persons", method = RequestMethod.GET) 
HttpEntity<PagedResources<Person>> persons(Pageable pageable, 
PagedResourcesAssembler assembler) { 


Page<Person> persons = repository.findAll(pageable); 
return new ResponseEntity<>(assembler.toResources(persons), HttpStatus.OK); 
d 
} 


上 面 的 toResources 方 法 会 执行 以 下 的 几 个 步骤 : 


e Page 对 象 的 content 会 转换 成 为 PagedResources 对 象 的 content。 

e PagedResources 会 的 到 一 个 PageMetadata 的 实体 ,包含 从 Page 跟 PageRequest 得 到 的 信 
息 。 

e PagedResources 会 根据 状态 得 到 prev 跟 next 链 接 , 这 些 链接 指向 URI 所 匹配 的 方法 。 分 页 
参数 会 根据 PageableHandlerMethodArgumentResolver 配 置 ,以 让 其 能 够 在 后 面 的 方法 中 
解析 使 用 。 


假设 我 们 数据 库 中 存 有 30 个 人 。 发 送 一 个 GET 请 求 http://localhost:8080/persons, 得 到 的 返回 
结果 如 下 : 


{ “links” : [ { "rel" : "next", 
"href" : "http://localhost :8080/persons?page=1&size=20 } 

1, 
"content" : [ 

. // 20 Person instances rendered here 
1, 
"pageMetadata" : { 

"size" : 20, 

"totalElements" : 30, 

"totalPages" : 2, 

"number" : 0 


从 返回 结果 中 可 以 看 出 assembler 生 成 了 正确 的 URI， 并 根据 默认 配置 设置 了 分 页 的 请 求 参 
数 。 这 意味 着 ， 如 果 我 们 更 改 了 配置 ， 这 个 链接 会 自动 更 改 。 默 认 情 况 下 ，assembler 生 成 的 
链接 会 指向 被 调用 的 controller 方 法 ， 但 也 可 以 通过 重 写 
PageResourceAssembler.toResourcet...} 方 法 提供 一 个 自 定义 的 链接 。 


QueryDSL web 支 持 


对 于 那些 集成 了 QueryDSL 的 存储 可 以 从 请 求 的 查询 参数 中 直接 获得 查询 语句 。 这 意味 着 下 
面 的 针对 User 的 请 求 参数 : 


?firstname=Dave&lastname=Matthews 


Ait QuerydslPredicateArgumentResolverf fr ER 


QUser.user.firstname.eq("Dave").and(QUser.user.lastname.eq("Matthews")) 


an SR FH T @EnableSpringDataWebSupportit ##, #EclasspathH & ZQuerydsl, FB 


么 该 功能 会 自动 开局 。 


在 方法 中 加 入 @Quweryas/Predicate 注 解 ， 可 以 提供 我 们 使 用 Preaicate 


@Controller 
class UserController { 


@Autowired UserRepository repository; 

@RequestMapping(value = "/", method = RequestMethod.GET) 

String index(Model model, @QuerydslPredicate(root = User.class) Predicate predicate, 
Pageable pageable, @RequestParam MultiValueMap<String, String> parameters) { 


model.addAttribute("users", repository.findAll(predicate, pageable)); 


return "index"; 


} 
1 解析 查询 参数 来 匹配 针对 User 的 Predicate 





默认 的 绑 定 如 下 : 


。 一 个 对 象 对 应 一 个 简单 属性 相当 于 eq 


?firstname=2 


e 多 个 属性 上 对 应 一 个 对 象 相 当 于 contains 


?firstname=2&firstname=3 


。 简单 属性 对 应 一 个 集合 相当 于 in 


?firstname=[2,3,4,5] 


这 些 绑 定 规则 可 以 通过 @QuerydslPredicate 的 bindings 属 性 或 者 使 用 Java 8 新 引入 的 qefault 方 
法 在 repository 接 口中 加 入 QuerydslBinderCustomizer 方 法 来 更 改 。 


interface UserRepository extends CrudRepository<User, String>, 
QueryDslPredicateExecutor<User>, //1 
QuerydslBinderCustomizer<QUser> { //2 


@Override 
default public void customize(QuerydslBindings bindings, QUser user) { 


bindings.bind(user.username).first ((path, value) -> path.contains(value)) a, 
bindings.bind(String.class) 

.first((StringPath path, String value) -> path.containsIgnoreCase(value)); / 
bindings.excluding(user.password); //5 


i.QueryDslPredicateExecutor provides access to specific finder methods for Predicate. 
2.QuerydslBinderCustomizer defined on the repository interface will be automatically pick 
3.Define the binding for the username property to be a simple contains binding. 

4.Define the default binding for String properties to be a case insensitive contains matc 
5.Exclude the password property from Predicate resolution. 


e -— 
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如 果 使 用 过 Spring 提供 的 JDBC 模 块 ， 可 能 会 对 使 用 SQL 脚本 填充 DataSource。Spring Data 
中 也 提供 了 相似 的 功能 来 填充 repository， 只 不 过 不 是 使 用 SQL， 而 是 使 用 XML 或 JSON 来 定 
义 数 据 ， 


假设 有 一 个 data.json 文 件 ， 内 容 如 下 : 


Example 29. Data defined in JSON (使 用 JSON 定 义 数据 ) 


[X classic: *com:acme-Person» 
"firstname" : "pave", 

"lastname" : "Matthews" }, 

{ "_class" : "com.acme.Person", 
"firstname" : "Carter", 

"lastname" : "Beauford" } ] 


为 了 把 前 面 定 义 的 数据 填充 到 PersonRepository 中 可 以 使 用 repository 命 名 空间 提供 的 
popilator 元 素 。 Example 30. Declaring a Jackson repository populator( 声 明 Jackson 
repository populator) 


<?xml version="1.0" encoding="UTF-8"?> 
«beans xmlns="http://www.springframework.org/schema/beans" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema- instance" 
xmlns:repository="http://www.springframework.org/schema/data/repository" 
xsi:schemaLocation="http://www.springframework.org/schema/beans 
http://www. springframework.org/schema/beans/spring-beans. xsd 
http://www. springframework.org/schema/data/repository 
http://www. springframework.org/schema/data/repository/spring-repository.xsd"> 


<repository:jackson2-populator locations="classpath:data.json" /> 


</beans> 


上 面 的 配置 会 让 data.jsom 文 件 可 以 在 其 他 地 方 通过 Jackson 的 Object Mapper 读 取 和 反 序 列 
化 。 


JSON object 的 类 型 可 以 通过 解析 json 文 件 中 的 _class 属 性 得 到 。Spring 框 架 会 根据 反 序 列 化 
的 对 象 选 择 合适 的 repository 来 处 理 。 


如 果 想 要 用 XML 来 定义 repositries 填 充 的 数据 ， 需 要 使 用 unmarshaller-populator 元 素 , 可 以 利 
用 Spring OXM 提 供 的 组 件 ， 想 要 详细 了 解 请 参考 Spring 参考 文档 : 


Example 31. Declaring an unmarshalling repository populator (using JAXB) 


Spring-Data-Elasticsearch 


<?xml version="1.0" encoding="UTF-8"?> 
«beans xmlns="http://www.springframework.org/schema/beans" 
xmlns:xsi-"http://www.w3.0rg/2001/XMLSchema-instance" 
xmlns:repository-"http://www.springframework.org/schema/data/repository" 
xmlns:oxm-"http://www.springframework.org/schema/oxm" 
xsi:schemaLocation-"http://www.springframework.org/schema/beans 
http://www.springframework.org/schema/beans/spring-beans.xsd 
http://www.springframework.org/schema/data/repository 
http://www.springframework.org/schema/data/repository/spring-repository.xsd 
http://www.springframework.org/schema/oxm 
http://www.springframework.org/schema/oxm/spring-oxm.xsd"- 


«repository:unmarshaller-populator locations="classpath:data.json" 
unmarshaller-ref="unmarshaller" /> 


<oxm:jaxb2-marshaller contextPath="com.acme" /> 


</beans> 


Repository 填 充 
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Elasticsearch Repositories 


这 一 章 会 详细 介绍 Elasticsearch repository & Io 


RA 


=~ 


Spring 命名 空间 


Spring Data Elasticsearch 模 块 包含 一 个 自 定 义 的 命名 空间 ， 它 允许 我 们 定义 repository bean 
和 初始 化 一 个 ElasticsearchServer。 


下 面 ， 我 们 像 创建 Repository 实 例 中 描述 的 那样 使 用 repositories 元 素 查 找 Spring Data 
repository。 


Example 32. Setting up Elasticsearch repositories using Namespace( 使 用 命名 空间 创建 
Elasticsearch repositories) 


<?xml version="1.0" encoding="UTF-8"?> 

«beans xmlns="http://www.springframework.org/schema/beans" 
xmlns:xsi-"http://www.w3.0rg/2001/XMLSchema-instance" 
xmlns:elasticsearch-"http://www.springframework.org/schema/data/elasticsearch" 
xsi:schemaLocation-"http://www.springframework.org/schema/beans 
http://www.springframework.org/schema/beans/spring-beans-3.1.xsd 
http://www.springframework.org/schema/data/elasticsearch 
http://www.springframework.org/schema/data/elasticsearch/spring-elasticsearch-1.0.xsd"» 


«elasticsearch:repositories base-package="com.acme.repositories" /> 
</beans> 
 ————SOelEm2»x)32am3€7 EEECEEEEEA E EE ZEE | 
f& FA Transport Client 和 Node Client 元 素 注册 一 个 Elasticsearch Server% fl. 


Example 33. Transport Client using Namespace( 使 用 Transport Client) 


<?xml version="1.0" encoding="UTF-8"?> 

«beans xmlns="http://www.springframework.org/schema/beans" 

xmlns :xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:elasticsearch-"http://www.springframework.org/schema/data/elasticsearch" 
xsi:schemaLocation-"http://www.springframework.org/schema/beans 
http://www.springframework.org/schema/beans/spring-beans-3.1.xsd 
http://www.springframework.org/schema/data/elasticsearch 
http://www.springframework.org/schema/data/elasticsearch/spring-elasticsearch-1.0.xsd"» 


«elasticsearch:transport-client id-"client" cluster-nodes="localhost : 9300, someip: 9300 


</beans> 


D We |: 





Example 34. Node Client using Namespace(f& Ħ Node Client) 


Spring-Data-Elasticsearch 


<?xml version="1.0" encoding="UTF-8"?> 

«beans xmlns="http://www.springframework.org/schema/beans" 
xmlns:xsi-"http://www.w3.0rg/2001/XMLSchema- instance" 
xmlns:elasticsearch-"http://www.springframework.org/schema/data/elasticsearch" 
xsi:schemaLocation="http://www.springframework.org/schema/beans 
http://www.springframework.org/schema/beans/spring-beans-3.1.xsd 
http://www.springframework.org/schema/data/elasticsearch 

http://www. springframework.org/schema/data/elasticsearch/spring-elasticsearch-1.0.xsd"> 


<elasticsearch:node-client id="client" local="true"" /> 


</beans> 


ZZ 
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基于 注解 的 配置 


Spring Data Elasticsearch repository 可 以 通过 XML 配置 ， 也 可 以 通过 JavaConfig 的 注解 配 
E. 


Example 35. Spring Data Elasticsearch repositories using JavaConfig(fi FH JavaConfig) 


@Configuration 
@EnableElasticsearchRepositories(basePackages = "org/springframework/data/elasticsearch/r 
static class Config { 

@Bean 

public ElasticsearchOperations elasticsearchTemplate() { 


return new ElasticsearchTemplate(nodeBuilder().local(true).node().client()); 





LEN is fih FH Elasticsearch Template &|& T — “Embedded Elasticsearch Server, EX 
@EnableElasticsearchRepositories}t f# e z Spring Data Elasticsearch Repositories, 20 
果 没 有 显 式 指定 扫描 的 包 路 径 ， 会 扫描 配置 类 所 在 的 包 。 


使 用 CDI 


Spring Data Elasticsearch repositories 也 可 以 使 用 CDI 注 入 。 


Example 36. Spring Data Elasticsearch repositories using JavaConfig (使 用 JavaConfig) 


class ElasticsearchTemplateProducer ( 


@Produces 
@ApplicationScoped 
public ElasticsearchOperations createElasticsearchTemplate() { 
return new ElasticsearchTemplate(nodeBuilder().local(true).node().client()); 


class ProductService { 
private ProductRepository repository; 
public Page<Product> findAvailableBookByName(String name, Pageable pageable) { 


return repository.findByAvailableTrueAndNameStartingwith(name, pageable); 


@Inject 
public void setRepository(ProductRepository repository) { 
this.repository = repository; 


查询 方法 


查询 策略 


Elasticsearch 模 块 支持 所 有 基本 查询 构建 ， 比 如 String,Abstract,Criteria 或 通过 方法 名 获得 构 
建 查询 。 
声明 查询 


通过 解析 方法 名 来 构建 查询 有 时 可 能 满足 不 了 开发 者 的 需求 ， 或 造成 方法 名 可 读 性 差 。 这 时 
可 以 使 用 @Quwery 注 解 来 声明 一 个 查询 (参考 使 用 @Query 注 解 ) 


创建 查询 


通常 情况 下 ,Elasticsearch 模 块 创建 查询 的 机 制 与 4.2 节 查询 方法 中 描述 的 一 样 。 通 过 下 面 的 例 
子 ， 我 们 来 看 看 Elasticsearch 模 块 会 根据 一 个 查询 方法 生成 怎样 的 查询 语句 。 


Example 37. Query creation from method names (通过 方法 名 创建 查询 ) 


public interface BookRepository extends Repository<Book, String> 
t 

List«Book» findByNameAndPrice(String name, Integer price); 
} 


根据 上 面 的 方法 名 会 生成 下 面 的 Elasticsearch 查 询 语句 


{ "bool" : 
{ "must" : 
[ 
ireld name al, 
{fel Ke pr dcos E 
] 
b 
} 


下 面 的 表格 列 出 了 所 有 Elasticsearch 支 持 的 关键 字 。 


Table 2. Supported keywords inside method names (方法 名 中 支持 的 关键 字 ) 


ix Elasticsearch & i4]; 
关键 字 例子 ^] 


bool" : ("must" : [ 
"field" : {"name" ` "?"}}, 


And findByNameAndPrice "field" : "price" : "2 中 
ID) 
{"bool" : {"should" : [ 
{"field" : {"name" : "?"}}, 
Or findByNameOrPrice field" : {"price” : "2"} 
ID) 
{"bool" : {"must" : 
Is findByName "field" ` {"name" : 
""y) 
{"bool" : ("must . not" : 
Not findByNameNot "field" ` {"name" : 


"zm 


LessThanEqual 


GreaterThanEqual 


Before 


After 


Like 


StartingWith 


EndingWith 


Contains/Containing 


findByPriceLessThan 


findByPriceGreaterThan 


findByPriceBefore 


findByPriceAfter 


findByNameLike 


findByNameStartingWith 


findByNameEndingWith 


findByNameContaining 


findByNameln(Collectionnames) 


{"bool" : "must" : 
{"range" : ("price" : 
{"from" : null,"to" : 
?,"include lower" : 
true,"include upper: 


true}}}}} 


{"bool" : {"must" : 
{"range" : ("price" : 
{"from" : ?,"to" : 
null,"include_lower" : 
true,"include upper" : 


true}}}}} 


{"bool" : {"must" : 
{"range" : ("price" : 
{"from" : null,"to" : 
?,"include_lower" : 
true,"include_upper" : 


true}}}}} 


{"bool" : {"must" : 
{"range" : ("price" : 
{"from" : ?,"to" : 
null,"include_lower" : 
true,"include upper: 


true}}}}} 


{"bool" : {"must" : 
"field" ` {"name" : 
{"query" : "2 


,analyze wildcard" : 


true}}}}} 


{"bool" : {"must" : 
"field" ` {"name" : 
{"query" : Um 


,analyze wildcard" : 


true}}}}} 


{"bool" : {"must" : 
"field" ` {"name" : 
{"query" : 

"*?" "analyze wildcard" 


: true}}}}} 


{"bool" : {"must" : 
"field" ` {"name" : 
{"query" : 

"2" "analyze_wildcard" 
: true}}}}} 

{"bool" : {"must" : 
{"bool" : "should" : [ 
"field" : {"name" : "?"}}, 


Notln 


Near 


True 


False 


OrderBy 


findByNameNotln(Collectionnames) 


findByStoreNear 


findByAvailableTrue 


findByAvailableFalse 


findByAvailableTrueOrderByNameDesc 


"field" : {"name" ` "?"}} 


mj 


{"bool" : ("must not" : 
{"bool" : "should" : 
"field" ` "name" : 
Mann 

暂 不 支持 


{"bool" : {"must" : 
"field" ` {"available" : 


true) 


{"bool" : "must" : 
"field" ` available" : 


false 


{"sort" H "name": 
{"order" ` "desc") 
}],"bool" : "must" : 
"field" ` {"available" : 


true) 


使 用 @Query 注 解 


Example 38. Declare query at the method using the @Query annotation.( 使 用 @Query 注 解 
声明 查询 ) 


public interface BookRepository extends ElasticsearchRepository<Book, String> { 
@Query("{"bool" : ["must" : {"field" : ["name" : "?0"}}}}") 
Page<Book> findByName(String name,Pageable pageable); 


其 他 Elasticsearch 操 作 的 支持 


这 一 章 会 讲解 无 法 通过 repository 接 口 直接 使 用 的 其 他 Elasticsearch 操 作 。 建 议 像 自 定义 
repository 实 现 这 章 中 描述 的 那样 为 repository 添 加 自 定 义 的 实现 。 


构建 Filter 


使 用 过 滤器 可 以 提高 查询 速度 


private ElasticsearchTemplate elasticsearchTemplate; 


SearchQuery searchQuery = new NativeSearchQueryBuilder() 
.WithQuery(matchAllQuery()) 
.withFilter(boolFilter().must(termFilter("id", documentId))) 
.build(); 


Page<SampleEntity> sampleEntities = 
elasticsearchTemplate.queryForPage(searchQuery, SampleEntity.class); 


fJ FAScanflScrollaERr 3 RE 


Elasticsearch 在 处 理 大 结果 集 时 可 以 使 用 scan 和 scroll。 在 Spring Data Elasticsearch#, TILL 
向 下 面 那 祥 使 用 ElasticsearchTemplate 来 使 用 scan 和 scroll 处 理 大 结果 集 。 


Example 39. Using Scan and Scroll( 使 用 scan 和 scroll) 


SearchQuery searchQuery = new NativeSearchQueryBuilder() 
.WithQuery(matchAllQuery()) 
.withIndices("test-index") 
.withTypes("test-type") 
.withPageable(new PageRequest(0,1)) 
.build(); 
String scrollId = elasticsearchTemplate.scan(searchQuery, 1000, false); 
List<SampleEntity> sampleEntities = new ArrayList<SampleEntity>(); 
boolean hasRecords = true; 
while (hasRecords){ 
Page<SampleEntity> page = elasticsearchTemplate.scroll(scrollId, 50001 , new ResultsM 


d 
@Override 
public Page<SampleEntity> mapResults(SearchResponse response) { 
List<SampleEntity> chunk = new ArrayList<SampleEntity>(); 
for(SearchHit searchHit : response.getHits()){ 
if(response.getHits().getHits().length <= 0) ( 
return null; 
} 
SampleEntity user = new SampleEntity(); 
user.setId(searchHit.getId()); 
user.setMessage( (String)searchHit.getSource().get("message")); 
chunk.add(user); 
j 
return new PageImpl<SampleEntity>(chunk); 
} 
1 


if(page !- null) ( 
sampleEntities.addAll(page.getContent()); 
hasRecords - page.hasNextPage(); 


} 
else{ 
hasRecords = false; 
} 
} 





附录 
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附录 A 命名 空间 参考 


元 素 
元 素 最 重要 的 属性 就 是 base-package, 用 来 定义 查找 Spring Data repository 接 口 时 扫描 包 的 路 
径 。 
Table 3. 属 性 
名 称 描述 


GE 定义 查找 所 有 继承 *Repository 的 repository 接 口 时 所 扫描 包 的 路 径 ， 该 
package — 路径 下 所 有 的 包 都 会 被 扫描 。 人 允许 使 用 通配符 


repository- 定义 自 定义 repository 实 现 类 的 后 级 。 所 有 名 字 是 以 指定 后 级 结尾 的 类 
impl-postfix 都 会 被 看 做 是 自 定义 repository 的 实现 类 。 上 默认 值 是 /mp/ 


query-lookup- 定义 创建 查询 语句 的 策略 ， 详 细 请 看 查询 策略 ,默认 采用 create-if-not- 
strategy found 策 略 


named- 

queries- 定义 包含 外 部 定义 好 的 查询 语句 的 Properties 文 件 的 位 置 

location 

consider- 

nested- 该 属性 的 值 决定 了 是 否 人 允许 定 义 府 套 的 repository 接 口 。 默 认 值 是 false 


repositories 


附录 B Populators 命 名 空间 参考 文档 


元 素 
允许 开发 者 通过 Spring Data repository 框 架 填 充 数据 存储 。 
Table 4.Attributes( 属 性 ) 

名 称 描述 


locations 定义 包含 用 来 读 取 填 充 对 象 的 文件 的 位 置 
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支持 的 查询 关键 字 


下 面 的 表格 列 出 了 Spring Data repository 查 询 解 析 机 制 支持 的 查询 关键 字 。 某 些 特定 的 存储 
可 能 不 支持 全 部 的 关键 字 。 


Table 5.Query keywords( 查 询 关 键 字 ) 


逻辑 关键 字 

AND 

OR 

AFTER 

BEFORE 
CONTAINING 
BETWEEN 
ENDING_WITH 
EXISTS 

FALSE 
GREATER_THAN 
GREATER_THAN_EQUALS 
IN 

IS 
IS_NOT_NULL 
IS_NULL 
LESS_THAN 
LESS THAN. EQUAL 
LIKE 

NEAR 

NOT 

NOT IN 

NOT LIKE 
REGEX 
STARTING. WITH 
TRUE 

WITHIN 


After, IsAfter 

Before, IsBefore 

Containing, IsContaining, Contains 
Between, IsBetween 

EndingWith, IsEndingWith, EndsWith 
Exists 

False, IsFalse 

GreaterThan, IsGreaterThan 
GreaterThanEqual, IsGreaterThanEqual 
In, Isin 

Is, Equals, (or no keyword) 

NotNull, ISNotNull 

Null, IsNull 

LessThan, IsLessThan 
LessThanEqual, IsLessThanEqual 
Like, IsLike 

Near, IsNear 

Not, IsNot 

Notln, IsNotln 

NotLike, IsNotLike 

Regex, MatchesRegex, Matches 
StartingWith, IsStartingWith, StartsWith 
True, IsTrue 


Within, IsWithin 


x 
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支持 的 查询 返回 类 型 


下 面 的 表格 列 出 了 Spring Data repositories 支 持 的 返回 类 型 。 某 些 特 定 的 存储 可 能 不 支持 全 部 
的 返回 类 型 。 


只 有 支持 地 理 空间 查询 的 数据 存储 才 支 持 GeoResult，GeoResults，GeoPage 等 返回 类 
型 


Table 6.Query return types( 查 询 返 回 值 ) 


返回 值 类 型 
void 
Primitives 


Wrapper types 
T 


lterator 
Collection 


List 


Optional 


Stream 


Future 


CompletableFuture 


ListenableFuture 


Slice 


Page 


GeoResult 
GeoResults 


GeoPage 


描述 

表示 没有 返回 值 
基本 的 Java 类 型 
Java 的 包装 类 


最 多 只 返回 一 个 实体 。 没 有 查询 结果 时 返回 null。 如 果 超 过 了 一 个 
结果 会 抛 出 IncorrectResultSizeDataAccessException 的 异常 


一 个 迭代 器 
一 个 集合 
一 个 列表 


返回 Java 8 或 Guava 中 的 Optional 类 。 查 询 方法 的 返回 结果 最 多 只 
能 有 一 个 。 如 果 超 过 了 一 个 结果 会 抛 出 
IncorrectResultSizeDataAccessException 的 异常 


Java 83| 入 的 Stream 类 


一 个 Future 类 ， 查 询 方法 需要 带 有 @Async 注 解 ， 并 开启 Spring 异 
步 执 行 方 法 的 功能 


返回 Java8 中 新 引入 的 CompletableFuture 类 ， 查 询 方 法 需要 带 有 
@Async 注 解 ， 并 开启 Spring 异 步 执行 方法 的 功能 


返回 org.springframework.util.concurrent.ListenableFuture 类 ， 查 
询 方 法 需要 带 有 @Async 注 解 ， 并 开启 Spring 异 步 执 行 方法 的 功能 


返回 指定 大 小 的 数据 和 是 否 还 有 可 用 数据 的 信息 。 需 要 方法 带 有 
Pageable 类 型 的 参数 


在 Slice 的 基础 上 附加 返回 总 数 等 信息 。 需 要 方法 带 有 Pageable 类 
型 的 参数 


返回 结果 会 附带 诸如 到 相关 地 点 距离 等 信息 
返回 GeoResult 的 列表 ， 并 附带 到 相关 地 点 平均 距离 等 信息 
分 页 返回 GeoResult， 并 附带 到 相关 地 点 平均 距离 等 信息 


